nMon Documentation

Thank you for purchasing nMon. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here.

Server Requirements

To run nMon your hosting server must support the following:

PHP version 5.4 or greater (PHP 7.1 recommended for best performance)
MySQL version 5.x or greater(MariaDB 10 recommended for best performance)
PHP PDO MYSQL extension;
PHP FSOCKOPEN enabled;
PHP EXEC enabled (optional for ping checks);
Cronjobs.

Installation

Folow these steps to install nMon:

STEP 1. Upload Files

Connect to your web server with your favorite FTP client (ie. Filezilla) and upload the contents of the ‘upload’ folder.

STEP 2. Create the Database

Create a new MySQL database using your host’s control panel.

STEP 3. Run the Installation Script

Point a web browser to your domain plus “/install” (example http://www.my-domain.com/install).

Enter your MySQL database configuration and enter the authentication details to create your first admin account.

nMon URL will be automatically determined, adjust if needed, (note: URL must end with the trailing slash "/").

Click “Continue” to proceed to the next step.

If the database connection was successful the following screen will appear. Click “Install” to complete the installation.
installer image

STEP 4. Delete ‘install’ Directory

Using your FTP client, delete the ‘install’ folder from your web server.

STEP 5. Configure System Cron Job

Sign in to nMon, navigate to System > Settings > Cron Jobs and follow the instructions on this page on how to configure the system cron job.


To access nMon point your browser to your installation domain and login with the credentials provided during installation.

Notice: The installer needs to have permission to create the "config.php" file in the root directory of the installation, if installation is unsuccessful create an empty config.php file and rerun the installer.

Upgrading

Follow these steps to upgrade nMon

STEP 1. Download

Download the new version and extract with your favorite file-archiver.

STEP 2. Backup

Backup all your files and your database.
You can use a FTP client to download all the files from your web server to your local computer.
For the database backup use the tools provided in the admin panel for your hosting account (usually PhpMyAdmin).

STEP 3. Upload

Upload the contents of the ‘upload’ folder to your web server with your favorite FTP client, overwriting all the files.
If you have made any custom modifications to nMon files, these will be overwritten.

STEP 4. Run the Upgrade Script

Point a web browser to your installation plus “/install/upgrade.php” (example http://www.my-domain.com/install/upgrade.php). This script will update the database to the required version.

STEP 5. Delete ‘install’ Directory

Using your FTP client delete the ‘install’ directory from your web server.

Moving to another host/server

Follow these steps to move nMon to another hosting account/server

STEP 1. Transfer files

Using a FTP client (eg. Filezilla) download all nMon files from the old server and then upload to the new server.

STEP 2. Transfer database

Backup the database from the old server using the database administration tools in your server's control panel (usually PhpMyAdmin).
Create a new database on the new server and restore the data from the backup file.

STEP 3. Update config.php file

Using your favorite text editor edit config.php (in the root directory of your installation) and update with the new database credentials.

STEP 4. Configure System Cron Job on the new server

Sign in to nMon, navigate to System > Settings > Cron Jobs and follow the instructions on this page on how to configure the system cron job.

STEP 5. Update nMon URL

If the URL has changed, sign in to nMon, navigate to System > Settings and update with your new URL.

In case of URL change you have to reinstall the agent on all servers.

System Cronjob

For normal system operation you need to configure the following cron job using you hosting/VPS control panel.

Configure one of the following (which works best for your environment). 

*/3 * * * * GET http://[replace with your url]/crons/cron.php >/dev/null 2>&1
or 
*/3 * * * * php -q [replace with full path]/crons/cron.php >/dev/null 2>&1
This cron job will process websites and checks, process alerts for all assets and send notifications if needed, every 3 minutes.

Performance Considerations

Although it is recommended to run the cron job every 3 minutes, you may choose to increase this if the cron job takes more time to complete (depending on the number of checks and server's performance).

Check in System > Logs > Cron Log the time it takes to complete each cron invocation, as a rule add 2 minutes to the last cron run time, round up and this is the number to set your cron job.

PHP's max_execution_time should be higher than the cron job run time, if you do not see any data in the cron log your cron job might be configured incorrectly or it does not have time to complete, restricted by max_execution_time.

Configuration

After installation go to System > Settings to configure nMon.

General

Go to ‘General’ tab to set your company info, records to display per page, system log retention period and a few other tweaks.

Monitoring

In ‘Monitoring’ tab you can adjust the default check timeout, default contact used for new checks, servers or websites.

Adjust the history retention for monitoring according to your preferences, keep in mind that the database can get large if you have a lot of servers and keep the logs for a long period.

Localisation

In ‘Localisation’ you can adjust: first day of the week, default language, timezone and the date format.

Changing the time zone often is not recommended as this will not change the existing datetime information in the database, system will recover shortly after new data is received or collected, but the old data will be offset by the timezone difference.

Please refer to the ‘Translating’ section of this documentation on how to translate and add new languages.

Email Settings

Go to ‘Email Settings’ tab to configure your mail server.

By default the app uses PHP mail() to send emails.

You can configure a SMTP server if required (recommended).

SMS Gateway

If you wish to send SMS alerts you will have to configure your SMS service provider here.
nMon currently supports Clickatell and SMS Global.
You need to have an account with API access at one of this provider.

Twitter

If you wish to send twitter alerts (direct messages) you will have to configure your twitter API credentials here.
Go to https://apps.twitter.com/ to add a new app, copy the consumer key and secret then inside the newly created app generate a new access token and copy it to nMon configuration.
Note: Twitter does not support sending direct messages to the same twitter account, you have to generate the API credentials from a different account from the one you intend to receive alerts.

Pushover

If you wish to send pushover notifications you will have to configure your Pushover Application API Token here.
Go to https://pushover.net/apps/build to create a new Pushover Application/Plugin.

Notification Templates

In ‘Notification Templates’ tab you can customize the email templates nMon sends to users.
Click on any notification to edit it’s content.

Cron Jobs

Please refer to 'System Cronjob' section of this documentation for more information.

Key Aspects

SERVERS

Server monitoring is done with the nMon Agent which can be installed on your server with just one shell command.
To add a new server go to Servers click on Add Server fill in the name and group for your server and click Add.
After adding a new server access the server page and you will be presented with the install command.

Note: A Data Loss alert is required to properly determine server's uptime (this alert is created by default while adding a new server).

nMon agent is a minimal bash script which will extract server metrics every minute and report back to nMon.
nMon agent can report the following metrics: CPU usage, load averages, RAM usage, network usage, disk usage, current running processes and basic server info like hostname, operating system, kernel, etc.
nMon agent is compatible with the following operating systems CentOS, Red Hat, Cloudlinux, Scientific Linux, Debian, Ubuntu, Fedora, SuSe, Slackware, Gentoo Linux, Arch Linux and other linux distributions/variations are supported but not tested.

WEBSITES

Use websites monitors to check the status of a given website, load time and check if a string is present or not.
Note: A HTTP Response Code != 200 alert is required to properly determine website's uptime (this alert is created by default while adding a new website monitor).

CHECKS

Using checks monitors you can check the status of the following service types:
- TCP (used to monitor the status of a TCP service like FTP, HTTP, SMTP services, etc.)
- UDP (used to monitor the status of a UDP service like DNS)
- ICMP (Ping) (monitor if a host is alive using the basic ping command, PHP's exec function must be allowed in order for this to work)
- DNS (monitor a DNS server for a response, you can use to monitor if the specified DNS server responds correctly for the given host)
- IP Blacklist (monitor if an IP address is blacklisted on the most common email blacklists)

Depending on the check's type the following data is collected: status, response time, blacklisted or not.
Note: A Check Offline alert is required to properly determine service uptime for TCP, UDP or PING checks (this alert is created by default while adding a new check).
Note: A DNS Lookup Failed alert is required to properly determine the DNS status for DNS checks (this alert is created by default while adding a new check).
Note: A Listed In Blacklist alert is required to properly determine the blacklist status for IP Blacklists checks (this alert is created by default while adding a new check).

ALERTING & INCIDENTS

nMon uses alerts to check the status of a given asset, when adding a new asset a few default alerts are created automatically.
These alerts are highly customizable. Go to the Alerting tab of any asset to add alerts or modify existing ones.

Alerts are processed every time the system cron runs, if any alert is trigered a new incident will be created and the selected contacts will be notified.
If the problem disappears, nMon will automatically close the incident and the selected contacts will be notified.

nMon supports the following notification channels: Email, SMS, Pushbullet, Twitter Direct Messages.

- Email - make sure email server settings are properly configured in system settings
- SMS - You can choose between the following SMS gateway providers: Clickatell, SMS Global. An account with API access and enough credit is required to use SMS notifications
- Pushbullet - Go to pushbullet.com to create a new account and retrieve your API key in your Pushbullet profile, no further configuration is necessary.
- Twitter - notifications are sent using direct messages, please see the Configuration section on how to configure twitter API.
- Pushover - Go to pushover.net to create a new account and retrieve your user key, Pushover Application Token has to be configured in System > Settings for pushover notifications to work.

Contacts can be added in Alerting > Contacts. Leave the field blank of any channel to disable alerts on that channel.
- Email Address - example: john@example.com
- Mobile Number - your mobile number in international format
- Pushbullet - your Pushbullet Account access token
- Twitter - your twitter username
- Pushover - your Pushover user key

PAGES

You can add public pages which will include an overview of your assets' status.
You can choose what assets will be included on any page and predefine a custom message and title for a page.

All pages are public (no authentication required to view), you may use the page's link to display on your website or include in a HTML iframe tag.

Translating

nMon uses an implementation of gettext to provide multilanguage support.

Gettext uses ".po" and ".mo" files to hold the translations.
".po" (Portable Object) is a text file that includes the original texts and the translations, this file can be used for editing.
".mo" (Machine Object) files are compiled and are easy for computers to read, this file is used by nMon to provide translations.

Follow these steps to translate nMon

  1. "template.po" file is provided in the "lang" folder
  2. Edit this file with a PO file editor
  3. Compile .mo file with your PO file editor, save your file in the following format languagecode.mo (example: en.po, fr.po, it.po etc.)
  4. Copy the .mo file in the "lang/overrides" folder of your nMon installation.
  5. Go to System > Settings > Localisation and add your new language, use the 2 letters language code for the code field.

To edit .po files you can use Poedit, a simple to use and free application.

Notice: As new features are added to nMon, new text strings might need translating, whith each new update, if new strings available, will be added to the template file. You can import them with Poedit in your language file.

Notice: Place all translation files in the "lang/overrides" folder. Placing them directly into the "lang" folder might get overwritten.

Notice: Language code must be the same as the filename (example: if you have the file fr.mo the code is fr).

Notice: If the system does not find the required string in your translation file it will use the default English for that string.

Notice: Users/Admins can set different languages, if preferred, which overrides the default language set in Settings > Localisation.




Many thanks to Abdullah Almsaeed for the beautiful AdminLTE theme.